/*
 * Project: Made 2 Order Software service package
 * Package: com.madetoordersoftware.service
 * File:    IAbstractDao
 * Created: May 24, 2010
 */

/**
 * Copyright (c) 2010 Made 2 Order Software, LLC
 *
 * All rights reserved. No part of this software may be reproduced, stored in a retrieval system, or
 * transmitted in any
 * form or by any means, without the prior written permission of Made 2 Order Software.
 *
 * You may not distribute the URL or redistribute the files to third parties. You may transfer the files onto
 * a single
 * storage device so long as you can prove ownership of the software. You may not reverse engineer, decompile,
 * or
 * disassemble the software or media files. You may not modify or translate the software or media, or
 * distribute copies
 * of the software or media without the written consent of Made 2 Order Software, LLC.
 */
package com.made2ordersoftware.service;

import com.made2ordersoftware.exceptions.DAOException;
import com.made2ordersoftware.service.exceptions.NonexistentEntityException;
import java.io.Serializable;
import java.util.List;
import javax.persistence.EntityExistsException;

/**
 * An abstract service layer class to help managed all data access objects.
 *
 * @param <T>
 * @param <ID>
 *
 * @author David Canning <dcannin@gmail.com>
 * @version 1.0.0
 */
public interface IAbstractDao<T, ID extends Serializable> {

    /**
     * Creates/Adds the entity object to the database.
     *
     * @param entity Object to be created/added to the data source.
     *
     * @throws EntityExistsException Thrown if the entity already exist in system.
     * @throws DAOException          Any other database exception caught during the transaction execution.
     */
    void create(T entity) throws EntityExistsException, DAOException;

    /**
     * Edits the entity object in the database.
     *
     * @param entity Object to be edited in the data source.
     *
     * @throws com.made2ordersoftware.service.exceptions.NonexistentEntityException
     *
     * @throws DAOException                                                         Any database exception
     *                                                                              caught during the
     *                                                                              transaction execution.
     */
    void update(T entity) throws NonexistentEntityException, DAOException;

    /**
     * Deletes the entity object in the data source. This method should be overridden in most cases as to not
     * truely delete record from database.
     *
     * @param entity Object being deleted.
     *
     * @throws com.made2ordersoftware.service.exceptions.NonexistentEntityException
     *
     * @throws DAOException                                                         Any other database
     *                                                                              exception caught during
     *                                                                              the transaction
     *                                                                              execution.
     */
    void delete(T entity) throws NonexistentEntityException, DAOException;

    /**
     * Finds entities of type <code>T</code> with id in the database.
     *
     * @param id Unique identifier of entity to return
     *
     * @return An entity of type <code>T</code>
     *
     * @throws DAOException Any database exception caught during the transaction execution.
     */
    T findEntity(Object id) throws DAOException;

    /**
     * Finds all entities of type <code>T</code> in the database.
     *
     * @return A list of all objects found in data source.
     *
     * @throws DAOException Any database exception caught during the transaction execution.
     */
    List<T> findEntities() throws DAOException;

    /**
     * Finds entities of type <code>T</code> within range that are in the database.
     *
     * @param maxResults  Total number of records (objects) to return.
     * @param firstResult Row number in database to start search.
     *
     * @return A list of objects found.
     *
     * @throws DAOException Any database exception caught during the transaction execution.
     */
    List<T> findEntities(int maxResults, int firstResult) throws DAOException;

    /**
     * Finds entities of type <code>T</code> within range that are in the database.
     *
     * @param all         boolean used to determine if all results should be returned (true) or a subset
     *                    (false) from minResults
     *                    to maxResults.
     * @param maxResult   Total number of records (objects) to return.
     * @param firstResult Row number in database to start search.
     *
     * @return A list of objects.
     *
     * @throws DAOException Any database exception caught during the transaction execution.
     */
    List<T> findEntities(boolean all, int maxResult, int firstResult) throws DAOException;

    /**
     * Returns the number of objects in the database.
     *
     * @return Number of objects found in data source.
     *
     * @throws DAOException Any database exception caught during the transaction execution.
     */
    int getEntityCount() throws DAOException;

}
